home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / varargs.man < prev    next >
Encoding:
Text File  |  1989-09-18  |  4.6 KB  |  133 lines
  1.  
  2.  
  3.  
  4. VARARGS               C Library Procedures                VARARGS
  5.  
  6.  
  7.  
  8. NNAAMMEE
  9.      varargs - handle variable argument list
  10.  
  11. SSYYNNOOPPSSIISS
  12.      ##iinncclluuddee <<vvaarraarrggss..hh>>
  13.  
  14.      _f_u_n_c_t_i_o_n(vvaa__aalliisstt)
  15.      vvaa__ddccll
  16.  
  17.      vvaa__lliisstt _p_v_a_r;
  18.  
  19.      vvaa__ssttaarrtt(_p_v_a_r);
  20.  
  21.      f = vvaa__aarrgg(_p_v_a_r, _t_y_p_e);
  22.  
  23.      vvaa__eenndd(_p_v_a_r);
  24.  
  25. DDEESSCCRRIIPPTTIIOONN
  26.      This set of macros provides a means of writing portable pro-
  27.      cedures that accept variable argument lists.  Routines hav-
  28.      ing variable argument lists (such as _p_r_i_n_t_f(3S)) but do not
  29.      use _v_a_r_a_r_g_s are inherently nonportable, since different
  30.      machines use different argument passing conventions.
  31.  
  32.      vvaa__aalliisstt is used in a function header to declare a variable
  33.      argument list.
  34.  
  35.      vvaa__ddccll is a declaration for vvaa__aalliisstt.  No semicolon should
  36.      follow vvaa__ddccll.
  37.  
  38.      vvaa__lliisstt is a type defined for the variable used to traverse
  39.      the list.  One such variable must always be declared.
  40.  
  41.      vvaa__ssttaarrtt(_p_v_a_r) is called to initialize _p_v_a_r to the beginning
  42.      of the list.
  43.  
  44.      vvaa__aarrgg(_p_v_a_r, _t_y_p_e) will return the next argument in the list
  45.      pointed to by _p_v_a_r.  _t_y_p_e is the type to which the expected
  46.      argument will be converted when passed as an argument.  In
  47.      standard C, arguments that are cchhaarr or sshhoorrtt are converted
  48.      to iinntt and should be accessed as iinntt, arguments that are
  49.      uunnssiiggnneedd cchhaarr or uunnssiiggnneedd sshhoorrtt are converted to uunnssiiggnneedd
  50.      iinntt and should be accessed as uunnssiiggnneedd iinntt, and arguments
  51.      that are ffllooaatt are converted to ddoouubbllee and should be
  52.      accessed as ddoouubbllee.  Different types can be mixed, but it is
  53.      up to the routine to know what type of argument is expected,
  54.      since it cannot be determined at runtime.
  55.  
  56.      vvaa__eenndd(_p_v_a_r) is used to finish up.
  57.  
  58.      Multiple traversals, each bracketed by vvaa__ssttaarrtt ...  vvaa__eenndd,,
  59.      are possible.
  60.  
  61.  
  62.  
  63. Sprite v1.0               17 July 1986                          1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VARARGS               C Library Procedures                VARARGS
  71.  
  72.  
  73.  
  74.      vvaa__aalliisstt must encompass the entire arguments list.  This
  75.      insures that a ##ddeeffiinnee statement can be used to redefine or
  76.      expand its value.
  77.  
  78.      The argument list (or its remainder) can be passed to
  79.      another function using a pointer to a variable of type
  80.      vvaa__lliisstt- in which case a call to vvaa__aarrgg in the subroutine
  81.      advances the argument-list pointer with respect to the
  82.      caller as well.
  83.  
  84. EEXXAAMMPPLLEE
  85.      This example is a possible implementation of _e_x_e_c_l(3).
  86.           ##iinncclluuddee <varargs.h>
  87.           ##ddeeffiinnee MAXARGS     100
  88.  
  89.           /*   execl is called by
  90.                     execl(file, arg1, arg2, ..., (char *)0);
  91.           */
  92.           execl(vvaa__aalliisstt)
  93.           vvaa__ddccll
  94.           {
  95.                vvaa__lliisstt ap;
  96.                cchhaarr *file;
  97.                cchhaarr *args[MAXARGS];
  98.                iinntt argno = 0;
  99.  
  100.                vvaa__ssttaarrtt(ap);
  101.                file = vvaa__aarrgg(ap, cchhaarr *);
  102.                wwhhiillee ((args[argno++] = vvaa__aarrgg(ap, cchhaarr *)) != (cchhaarr *)0)
  103.                     ;;
  104.                vvaa__eenndd(ap);
  105.                rreettuurrnn execv(file, args);
  106.           }
  107.  
  108. BBUUGGSS
  109.      It is up to the calling routine to specify how many argu-
  110.      ments there are, since it is not possible to determine this
  111.      from the stack frame.  For example, _e_x_e_c_l is passed a zero
  112.      pointer to signal the end of the list.  _P_r_i_n_t_f can tell how
  113.      many arguments are supposed to be there by the format.
  114.  
  115.      The macros _v_a__s_t_a_r_t and _v_a__e_n_d may be arbitrarily complex;
  116.      for example, _v_a__s_t_a_r_t might contain an opening brace, which
  117.      is closed by a matching brace in _v_a__e_n_d.  Thus, they should
  118.      only be used where they could be placed within a single com-
  119.      plex statement.
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0               17 July 1986                          2
  130.  
  131.  
  132.  
  133.